Skip to content

docs(ia): audience-first navigation — Learn/Build/Operate/Extend sections + business-facing entry pages - #3423

Merged
os-zhuang merged 7 commits into
mainfrom
docs/audience-first-ia
Jul 24, 2026
Merged

docs(ia): audience-first navigation — Learn/Build/Operate/Extend sections + business-facing entry pages#3423
os-zhuang merged 7 commits into
mainfrom
docs/audience-first-ia

Conversation

@os-zhuang

Copy link
Copy Markdown
Contributor

Why

The docs site reads developer-only: 14 top-level sections in one flat sidebar (155+ pages), contributor content (kernel/protocol/plugins) at the same level as user content, cheatsheets crowding getting-started, and no entry point at all for evaluators or visual-tool builders — even though Studio/Console is half the product. Follow-up to the 2026-07 module-based IA migration, this pass answers "who is reading?".

What

Navigation (config-only, zero URL churn)

  • Root sidebar split into four audience sections via separators: Learn (getting-started, concepts) / Build (data-modeling, ui, automation, permissions, ai, api — ui moved before automation so readers see results early) / Operate (deployment) / Extend & Reference (plugins, kernel, protocol, references, releases)
  • getting-started split into Start Here / Cheatsheets subsections
  • ui section renamed Views & Apps (nav + home cards); prose keeps "UI Engine (ObjectUI)" as the engine name

Two tooling pages rehomed (the only moves)

  • getting-started/clideployment/cli, getting-started/validating-metadatadeployment/validating-metadata
  • redirects added; the pre-2026-07 guides/validating-metadata redirect retargeted to avoid a chain; all in-content links rewritten (12 files)

New audience pages

  • getting-started/platform-capabilities — business-language capability tour (data, views, automation, approvals, permissions, analytics, AI, integrations) with HotCRM as the clickable running example
  • getting-started/build-without-code — what admins/analysts do in Console, Studio (4 pillars, draft→publish, same validation gate), Setup, and Marketplace
  • concepts/index gains Find Your Path cards routing four reader personas

Verification

  • pnpm --filter @objectstack/docs build passes
  • Browser-checked on a local dev server: four sidebar sections render, Start Here/Cheatsheets grouping renders, both new pages render with full TOC, Find Your Path cards render, and /en/docs/getting-started/cli 308s to /docs/deployment/cli

Out of scope / follow-ups

  • i18n: the cn language is enabled in config but has zero content — needs a product decision (fill Learn-section first vs. disable the toggle)
  • True fumadocs sidebar tabs would need root-folder restructuring (URL churn); separators deliver the same grouping without it — revisit only if tab UX is wanted

🤖 Generated with Claude Code

…ions + business-facing entry pages

- Root sidebar split into four audience sections via separators (zero URL churn)
- getting-started split into Start Here / Cheatsheets; CLI and Validating
  Metadata moved to Deployment & Operations with redirects (incl. chain fix
  for the pre-2026-07 guides redirect) and in-content link rewrites
- New: getting-started/platform-capabilities (business-language capability
  tour, HotCRM as running example) and getting-started/build-without-code
  (Studio/Console/Setup visual-building guide)
- concepts/index gains Find Your Path reader cards; ui section renamed
  'Views & Apps' in nav and home cards

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vercel

vercel Bot commented Jul 23, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
spec Ready Ready Preview, Comment Jul 24, 2026 11:53am

Request Review

The cn language was declared in docs.site.json and mapped in middleware, but
lib/i18n.ts (what fumadocs actually consumes) only ever listed en and there is
zero cn content — a config-vs-runtime drift that made the site look bilingual.
Remove the declaration and the dead zh->cn Accept-Language mapping; keep the
i18n plumbing so a future language is content + one config line.

Verified: docs build passes; with Accept-Language: zh-CN, /docs serves the
English page with no /cn redirect.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Feedback pass on the audience-first IA: the sidebar still read as crowded.
- Drop the hardcoded Docs/Blog links above the tree (layout.shared.tsx)
- Strip per-item icons from all 14 section meta.json files (text-only tree)
- Merge the one-item Operate section: Learn / Build / Platform
- Take References and Releases (lookup content, 22 generated/log pages) out
  of the tree — URLs still resolve (verified 200) and the docs home page
  links both; getting-started no longer defaultOpen so the first screen
  shows all twelve top-level entries at once

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
'What Can It Do?' and 'Build Without Code' were buried inside the
Get Started folder — the exact audience they serve would never expand it.
Promote both to top-level Learn entries (/docs/platform-capabilities,
/docs/build-without-code; new-in-this-PR pages, so no redirects needed),
and lead the docs-home 'Start here' list with them.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
'What Can It Do?' grows from one page into a Learn-section folder of ten
business-language pages — data, views, forms & quality, automation,
approvals, permissions, analytics, AI, integrations & everyday work, and a
requirements one-pager template. Each page keeps three anchors: business
scenarios, an 'In HotCRM' pointer at the running example, and a
'For developers' cross-link into the technical Build docs. The index
becomes a card directory; new pages drop hand-written H1s (frontmatter
title renders them). URL /docs/platform-capabilities → /docs/capabilities
(page introduced in this PR, so no redirect debt).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… src/flows)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The page moved getting-started → deployment in this PR; its single
pre-existing occurrence (a table header) moves with it. Net change zero.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@os-zhuang
os-zhuang merged commit e43626a into main Jul 24, 2026
15 checks passed
@os-zhuang
os-zhuang deleted the docs/audience-first-ia branch July 24, 2026 12:11
os-zhuang pushed a commit that referenced this pull request Jul 29, 2026
…tore, first docs sweep

Three related closures on the just-merged v17 release page (#3906):

1. The Console section was missing 25 objectui commits. The v17 frontend window
is cf2d56e32a11 → 4a4829d0ef39 = 128 commits, but the pending console-*.md
changesets covered only 103: the range 2cb8d78e24ad...c6cfdf1288b6 landed with
no changeset — exactly the "SHA bump leaves no trace" failure
scripts/bump-objectui.sh exists to prevent. Two of the missing commits are
breaking and each is the frontend half of a backend change the page already
documented (useClientNotifications delegates ↔ #3612 SDK removal;
@object-ui/types Capabilities re-exports ↔ the retired capabilities cluster).
Both now sit beside their backend halves and in the upgrade checklist, with the
other eight substantive commits folded into the Console section and
.changeset/console-c6cfdf1288b6-backfill.md recording the range itself.

2. "releases" returns to the root sidebar. #3423 unlisted References and
Releases together ("lookup content ... the docs home page links both"); that
trade holds for References (22 generated pages) but not for Releases in a
release window, when the upgrade notes are what people open the docs for.
References stays out. check-release-notes now enforces what its success line
already claimed: the section must be reachable via the root nav OR a
/docs/releases link on the docs home — either satisfies it (preserving #3423's
option), losing both fails the build. Negative-tested both directions.

3. First v17 docs sweep (docs/v17-docs-sweep.md — playbook + append-only run
log with a watermark, built to re-run while the RC train iterates). Run 1
fixed the drift v17 left in hand-written prose: services-checklist (17→16
services, graphql rows, the dissolved ObjectStackProtocol), the anonymous-deny
matrix still listing /graphql + handleGraphQL, sharing docs describing
owner/group shapes as "declared but not enforced" (they no longer parse),
http-protocol claiming enable.trash exists, REST/GraphQL in objectql
diagrams/prose, and the objectstack-api skill description (mirrors regenerated
via gen:skill-docs). False positives and out-of-scope findings (spec comment
drift, implementation-status.mdx staleness) are logged for the next run.

Verified: pnpm docs:build passes; check:release-notes / doc-authoring /
role-word / org-identifier / nul-bytes / skill-docs-sync all green; the new
guard branch fails when both entry points are removed and passes with either.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LXvaYR7TiJBCxYwjn51owH
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/l tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant